istanbul-lib-instrument

What is istanbul-lib-instrument?

The 'istanbul-lib-instrument' package is a core library for instrumenting JavaScript code for coverage analysis. It is part of the Istanbul toolset, which is widely used for code coverage reporting in JavaScript projects. The library provides functionality to instrument code, which means it adds additional code to track which parts of the original code are executed during a test run.

What are istanbul-lib-instrument's main functionalities?

Instrumenting Code

This feature allows you to instrument JavaScript code. The `createInstrumenter` function creates an instrumenter instance, which can then be used to instrument code synchronously using the `instrumentSync` method. The instrumented code will include additional statements to track execution.

const { createInstrumenter } = require('istanbul-lib-instrument');
const instrumenter = createInstrumenter();
const originalCode = 'function add(a, b) { return a + b; }';
const instrumentedCode = instrumenter.instrumentSync(originalCode, 'filename.js');
console.log(instrumentedCode);

Generating Coverage Maps

This feature allows you to generate a coverage map for the instrumented code. After instrumenting the code, you can call the `lastFileCoverage` method to get a coverage map, which provides detailed information about which parts of the code were executed.

const { createInstrumenter } = require('istanbul-lib-instrument');
const instrumenter = createInstrumenter();
const originalCode = 'function add(a, b) { return a + b; }';
instrumenter.instrumentSync(originalCode, 'filename.js');
const coverageMap = instrumenter.lastFileCoverage();
console.log(coverageMap);

Other packages similar to istanbul-lib-instrument

nyc

NYC is a command-line interface for Istanbul. It provides a higher-level interface for running tests and generating coverage reports. While 'istanbul-lib-instrument' is focused on the low-level task of instrumenting code, NYC provides a more user-friendly way to integrate coverage reporting into your workflow.

babel-plugin-istanbul

Babel-plugin-istanbul is a Babel plugin that instruments code using Istanbul. It is designed to work with Babel, making it easy to integrate code coverage into projects that use Babel for transpilation. This plugin is useful if you are already using Babel and want to add coverage instrumentation as part of your build process.

c8

C8 is a code coverage tool that uses V8's built-in coverage collection. It provides a modern alternative to Istanbul-based tools by leveraging the native coverage capabilities of the V8 JavaScript engine. C8 can be a good choice if you are looking for a tool that integrates closely with Node.js and V8.

README

istanbul-lib-instrument

Istanbul instrumenter library.

Version 1.1.x now implements instrumentation using Babel. The implementation is inspired by prior art by @dtinth as demonstrated in the __coverage__ babel plugin.

It provides 2 "modes" of instrumentation.

• The old API that is mostly unchanged (except for incompatibilities noted) and performs the instrumentation using babel as a library.

• A programVisitor function for the Babel AST that can be used by a Babel plugin to emit instrumentation for ES6 code directly without any source map processing. This is the preferred path for babel users. The Babel plugin is called babel-plugin-istanbul.

Incompatibilities and changes to instrumentation behavior can be found in v0-changes.md.